/*
 * Package il.ac.biu.cs.grossmm.api.data
 * File SubscriptionPoint.java
 * 
 * This is a part of presence service framework API. 
 * See javadoc for more information.
 *  
 * Copyright (C) 2006 Grossmann Mark
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.

 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 
 * MA  02110-1301, USA.
 */

package il.ac.biu.cs.grossmm.api.flow;

import il.ac.biu.cs.grossmm.api.data.Root;
import il.ac.biu.cs.grossmm.api.keys.Key;

/**
 * API to access subscription point. Subscription point is an input active data
 * exchange point. It is always linked to a suibsciber. Subscription point
 * accepts subscriptions to data nodes with specified keys and sends
 * notifications about existance of data node and data modifications to the
 * subscriber.
 * 
 * The following diagram illustrates a possible sequence of operations:
 * 
 * <pre>
 *              
 *                   +---------------+                     +--------------+ 
 *                   |  Subscriber   |                     | Subscription | 
 *                   |               |                     |    point     |
 *                   +---------------+                     +--------------+
 *                           |                                     |
 *                           |                                     |   (no data associated
 *                           |---------- subscribe (key)----------&gt;|    with the key, access
 *                           |                                     |    denied or data cannot
 *                           |                                     |    be accessed for another
 *                           |&lt;-----deactivated (key, status)------|    reason)
 *                           |                                     |    
 *                           |&lt;----------activated (key)-----------|   (data has been
 *                           |- - - - - -  [node] - - - - - - - - &gt;|    associated with key)
 *                           |                                     |    
 *                           |&lt;----------activated (key)-----------|   (data modified)
 *                           |- - - - - -  [node] - - - - - - - - &gt;|
 *                           |                                     |
 *                           |-----------readLock (node)----------&gt;|    		
 *                           |       ... ( read  data ) ...        |
 *                           |----------readUnlock (node)---------&gt;|
 *                           |                                     |
 *                           |                                     |
 *                           |                                     |
 *                           |&lt;-----notify (node, inspector)-------|   (data modified)  		
 *                           |   ... ( inspect modifications) ...  |
 *                           | - - - - - - - - - - - - - - - - - -&gt;|
 *                           |                                     |
 *                           |                                     |
 *                           |                                     |
 *                           |&lt;-----notify (node, inspector)-------|   (data modified)  		
 *                           |   ... ( inspect modifications) ...  |
 *                           | - - - - - - - - - - - - - - - - - -&gt;| 
 *                           |                                     |
 *                           |                                     |
 *                           |&lt;-----deactivated (key, status)------|   (data removed, 
 *                           |                                     |    access denied, etc)
 *                                     ... ... ... ... ... 
 *                           |                                     |
 *                           |                                     |
 *                           |                                     |
 *                           |--------unsubscribe (key)-----------&gt;| 
 * </pre>
 */
public interface SubscriptionPoint<N> {

	// Removed
	// /**
	// * Queries for type of nodes which can be subscribed via this
	// * subscription point
	// *
	// * @return node type associated with this subscription point
	// */
	// NodeType<N> getNodeType();

	/**
	 * Subscribes to data associated with the given key
	 * 
	 * @param key
	 *            the key associated with data to subscribe to
	 * @param track
	 *            subscription tracker
	 * @return status of the subscription, if no output point matched
	 * to this subscription returns <tt>Status.UNMATCH</tt>
	 */
	Status subscribe(Key key, Track track);

	/**
	 * Unsubscribe from previously subscribed data associated with the given key
	 * 
	 * @param key
	 *            the key associated with data to unsubscribe from
	 */
	void unsubscribe(Key key);

	/**
	 * Get a subscribed data node by key. The key should refer to a subscribed
	 * node. Otherwise the method returns <tt>null</tt> even if node exists.
	 * 
	 * @param key
	 *            the key
	 * @return subscribed data node
	 */
	Root<N> getRoot(Key key);

	/**
	 * Gets the subscription state for given key. Returns null if there's
	 * subscription associated with the key
	 * 
	 * @param key
	 *            the key to get the subscription state for
	 * @return the subscription state for given key or null if there's
	 *         subscription associated with the key
	 */
	Status getSubscriptionState(Key key);

	/**
	 * Fetch data associated with the given key (not necessarily subscribed).
	 * This method returns null if no data node is associated with the key. In
	 * case there's no subscription to the key this method invocation may take a
	 * long time (comparible to <tt>subscribe</tt> method).
	 * 
	 * @param key
	 *            the key associated with data to fetch
	 * @return fetched data node, or null if no data is currently associated
	 *         with the key
	 */
	Root<N> fetch(Key key);

	/**
	 * Starts read-data transaction
	 * 
	 * @param node
	 *            root data node to read
	 * @return node inspector to use in this transaction
	 */
	NodeInspector readLock(Root<N> node);

	/**
	 * Ends read-data transaction
	 * 
	 * @param node
	 *            root data node
	 */
	void readUnlock(Root<N> node);
}
